Expose response headers in DocsService - #6191

We should return ResponseData to preserve the header ordering and support multi-value headers. By doing so, we can remove extractHeaders below as well.

Thanks for your review ! Belows are the changes :

1. Introduced ResponseData to handle response (body + headers).
2. Implemented multi-value headers handling using Map<string, string[]>.
3. Updated header display logic in DebugPage to follow RFC9110 §5.2 guidelines.

RFC9110 specifies:

"A sender MUST NOT generate multiple header fields with the same field name unless the entire field value is comma-separated or the field explicitly allows multiple field lines."

Thus, I defined ResponseData in types.tsx as:

https://github.com/hyunw9/armeria/blob/9705ab2a375c66f0f383edfd526249c5f7f6c150/docs-client/src/lib/types.ts#L28-L31

Replaced Response with <ResponseData> in abstract doSend<Response>, and aggregated response headers:

https://github.com/hyunw9/armeria/blob/9705ab2a375c66f0f383edfd526249c5f7f6c150/docs-client/src/lib/transports/annotated-http.ts#L126-L133

Adjusted DebugPage header display:

https://github.com/hyunw9/armeria/blob/9705ab2a375c66f0f383edfd526249c5f7f6c150/docs-client/src/containers/MethodPage/DebugPage.tsx#L664-L672

When server set headers like this :

final HttpHeaders headers = HttpHeaders.builder()
                                         .add("x-role", "admin")
                                         .add("x-role", "editor")
                                         .add("x-role", "user")
                                         .build();

Now, multi-value headers appear correctly as below:

Response Headers

If you have any feedback or suggestions, I’d really appreciate your comments!

Thanks! It looks much better. However, I'd like you to consider the following:

• The RFC you mentioned doesn't prohibit specifying multiple header values with the same header name if the multiple field lines are allowed explicitly.
• At the protocol level, these two are different:

  x-role: admin, editor, user
  

  vs.

  x-role: admin
  x-role: editor
  x-role: user
  

Therefore, what do you think about using plaintext rather than JSON to render the response headers?

Please also note that the following are considered different, although they are semantically same:

x-role: admin
other-header: other value
x-role: user

vs.

x-role: admin
x-role: user
other-header: other value

.. which means we need to preserve the ordering, which cannot be achieved by using a Map.

Initially, I didn’t consider the preservation of header order or merging rules.
However, after reviewing RFC 9110, I found that only headers defined using the #element syntax are safe to merge using commas.
For other headers, merging can result in loss of semantics or parsing errors.

For example, the Date header value like "Sat, 19 Apr 2025 09:00:00 GMT" includes a comma as part of the value.
Blindly splitting on commas would incorrectly produce lines like:

date: Sat
date: 19 Apr 2025 09:00:00 GMT

Initially, I implemented naive comma-splitting across all headers.
After identifying this issue, I refined the logic to selectively split only list-type headers, while preserving others unchanged.

The updated logic iterates through the response Headers object:

1. If a header is recognized as a list-type (e.g., Accept, Cache-Control), it splits the value by comma and renders each entry individually.

2. Otherwise, it preserves the header as a single line to avoid unintended splitting.

Example

It would be more useful if we could record the execution time and display it in the debug console. Some may want to know whether the response is outdated or up-to-date.

I think showing the execution time on the debug page could improve the user experience!

If we decide to display it, where would be the best place to show the execution time?
I was thinking of showing it in a separate section, similar to other API testing tools.

It sounds good to me. Could you prototype your idea? I’d like to see how it looks and feels.

In modern API Testing tools, they display Response status, execution time, and ResponseData size.

So i was thinking what if we displayed those three information on the right section of response page Util.

Examples :

Postman	Bruno

Prototype :

ResponsePage	DebugConsole

More specifically, I thought of two possible versions :

Text-like	Colored

--- Updated ---
I put together a quick prototype implementation. Let me know what you think !

Fail	Success

Executed time should be rounded tho :)

The prototype looks great! Since the results are cached, would you mind also adding the timestamp of when the request was executed?

Sure! It’s necessary when we’re caching ResponseData.
I’ve just added the update :)

1. As previously discussed, the cache now stores the entire ResponseData object instead of selected values.
2. Updated the DebugPage to display the newly added fields from ResponseData. The logic for determining colors is as follows: Diff

Here are some examples pictures:

2xx	4xx	Invalid